Lua utility module `EventSequence`

A chain of functions to call at specified times, modeled after TRNG's organizers.

Works atop the Timer, and so is updated automatically pre-OnControlPhase, and saved automatically when the game is saved. The sequence can be paused, unpaused, stopped, and started, and can be set to loop.

To use EventSequence inside scripts you need to call the module:

local EventSequence = require("Engine.EventSequence")

Example usage:

local EventSequence = require("Engine.EventSequence")

-- These will be called by the sequence
LevelFuncs.HealLara = function()
    Lara:SetHP(Lara:GetHP()+10)
end

local nSpawned = 0
LevelFuncs.SpawnBaddy = function(baddy, name, pos)
    local myBaddy = TEN.Objects.Moveable(baddy, name..nSpawned, pos, nil, 0)
    myBaddy:Enable()
    nSpawned = nSpawned + 1
end

-- This function triggers the sequence
LevelFuncs.TriggerSequence = function(obj)
    local posSteve = TEN.Objects.GetMoveableByName("stevePosNullmesh"):GetPosition()
    local posChris = TEN.Objects.GetMoveableByName("chrisPosNullmesh"):GetPosition()
    if not EventSequence.IfExists("my_seq") then
        EventSequence.Create("my_seq",
            false, -- does not loop
            {seconds = true, deciseconds = true}, -- timer format, see Timer for details
            6, -- seconds until call the function specified in next arg
            LevelFuncs.HealLara, -- first function to call. If we don't need to pass any arguments, we can just pass the function
            2.1, -- seconds until the next function, after the previous one has been called
            {LevelFuncs.SpawnBaddy, TEN.Objects.ObjID.BADDY1, "steve", posSteve}, -- if we DO want to pass arguments to the function to be called, we give a table with the function (LevelFuncs.SpawnBaddy in this case) followed by the args to pass to it
            0.5,
            {LevelFuncs.SpawnBaddy, TEN.Objects.ObjID.SAS_CAIRO, "chris", posChris},
            1,
            LevelFuncs.HealLara)
    end

    -- event sequences are inactive to begin with and so need to be started
    EventSequence.Get("my_seq"):Start()
end

Functions

Create(name, loop, timerFormat, ...)	Create (but do not start) a new event sequence.
Get(name)	Get an event sequence by its name.
IfExists(name)	Check if an event sequence exists.
Delete(name)	Delete an event sequence.

Class EventSequence

EventSequence:Start()	Begin or unpause a sequence.
EventSequence:SetPaused(p)	Pause or unpause the sequence.
EventSequence:Stop()	Stop the sequence.
EventSequence:IsPaused()	Returns whether the sequence is paused.
EventSequence:IsActive()	Returns whether the sequence is active.

Functions

Create(name, loop, timerFormat, ...)

Create (but do not start) a new event sequence.

Parameters:

name string A label to give the sequence; used to retrieve the timer later as well as internally by TEN.
loop bool If true, the sequence will start again from its first timer once its final function has been called.
timerFormat table or bool Same as in Timer format for Timer. This is mainly for debugging. This will not work properly if another sequence or timer is showing a countdown.
... float, LevelFuncs or table A variable number of pairs of arguments, each pair consisting of:
- a time in seconds (positive values are accepted and with only 1 tenth of a second [0.1]),
- followed by the function defined in the LevelFuncs table to call once the time has elapsed,
- followed by another duration in seconds, another function name, etc.

You can specify a function either by its name, or by a table { } with the function name as the first member, followed by its arguments (see example).

Returns:

EventSequence

Usage:

local EventSequence = require("Engine.EventSequence")
local TimerFormat = {seconds = true, deciseconds = true}

-- Example 1 function without arguments:
-- This creates a sequence that calls LevelFuncs.Func after 2 seconds
-- then LevelFuncs.Func after 3 seconds
-- and finally LevelFuncs.Func after 4 seconds
LevelFuncs.Func = function ()
   local pos = TEN.Vec2(TEN.Util.PercentToScreen(50, 10))
   local str = TEN.Strings.DisplayString("Repeated function without arguments", pos, 1)
   TEN.Strings.ShowString(str, 1)
end
EventSequence.Create(
   "test1", -- sequence's name
   true, -- loop
   TimerFormat, -- timer format
   2.0,  -- seconds until call the function
   LevelFuncs.Func, -- first function to call
   3.0,
   LevelFuncs.Func,
   4.0,
   LevelFuncs.Func)

-- Example 2 function with arguments:
-- This creates a sequence that calls LevelFuncs.Func2("1", 5, 10) after 2.3 seconds
-- then LevelFuncs.Func2("2", 5, 15) after 3.1 seconds
-- and finally LevelFuncs.Func2("3", 5, 20) after 4.8 seconds
LevelFuncs.Func2 = function (text, x, y)
   local pos = TEN.Vec2(TEN.Util.PercentToScreen(x, y))
   local str = TEN.Strings.DisplayString("Function " .. text .. "!", pos, 1)
   TEN.Strings.ShowString(str, 1)
end
EventSequence.Create(
   "test2", -- sequence's name
   true, -- loop
   false, -- no countdown is displayed
   2.3,
   {LevelFuncs.Func2, "1", 5, 10},
   3.1,
   {LevelFuncs.Func2, "2", 5, 15},
   4.8,
   {LevelFuncs.Func2, "3", 5, 20})

Get(name)

Get an event sequence by its name.

Parameters:

name string The label that was given to the sequence when it was created.

Returns:

EventSequence or nil

nil

Usage:

-- Example:
EventSequence.Get("my_seq")

IfExists(name)

Check if an event sequence exists.

Parameters:

name string The label that was given to the event sequence when it was created.

Returns:

bool

true

false

Usage:

-- Example:
-- This function checks if an event sequence named "my_seq" exists and starts it
LevelFuncs.CheckAndStart = function()
   if EventSequence.IfExists("my_seq") then
      EventSequence.Get("my_seq"):Start()
   end
end

Delete(name)

Delete an event sequence.

Parameters:

name string The label that was given to the event sequence when it was created.

Usage:

-- Example:
EventSequence.Delete("my_seq")

Class EventSequence

List of all methods of the EventSequence object. It is always recommended to check the existence of a sequence with the EventSequence.IfExists() function before using methods, to avoid errors or unexpected behavior. When calling a method, it is recommended to use the EventSequence.Get() function, to avoid errors after loading a save game.

Usage:

-- Examples of some methods
EventSequence.Get("my_seq"):Start()
EventSequence.Get("my_seq"):Stop()
EventSequence.Get("my_seq"):SetPaused(true)

-- check if sequence exists before using methods
if EventSequence.IfExists("my_seq") then
   EventSequence.Get("my_seq"):Start()
end

EventSequence:Start()

Begin or unpause a sequence. If showing the remaining time on-screen, its color will be set to white.

Usage:

-- Example:
if EventSequence.IfExists("my_seq") then
   EventSequence.Get("my_seq"):Start()
end

EventSequence:SetPaused(p)

Pause or unpause the sequence. If showing the remaining time on-screen, its color will be set to yellow (paused) or white (unpaused).

Parameters:

p bool If true, the sequence will be paused; if false, it will be unpaused.

Usage:

-- Example 1: Pause the sequence
if EventSequence.IfExists("my_seq") then
   EventSequence.Get("my_seq"):SetPaused(true)
end

-- Example 2: Unpause the sequence
if EventSequence.IfExists("my_seq") then
   EventSequence.Get("my_seq"):SetPaused(false)
end

EventSequence:Stop()

Stop the sequence.

Usage:

-- Example:
EventSequence.Get("my_seq"):Stop()

EventSequence:IsPaused()

Returns whether the sequence is paused.

Returns:

bool

true

false

Usage:

-- Example 1: paused sequence
if not EventSequence.Get("my_seq"):IsPaused() then
   EventSequence.Get("my_seq"):SetPaused(true)
end

-- Example 2: unpause the sequence
if EventSequence.Get("my_seq"):IsPaused() then
   EventSequence.Get("my_seq"):SetPaused(false)
end

EventSequence:IsActive()

Returns whether the sequence is active.

Returns:

bool

true

false

Usage:

-- Example:
if not EventSequence.Get("my_seq"):IsActive() then
   EventSequence.Get("my_seq"):Start()
end

TombEngine

1 Modules

2 Classes

3 Primitive Classes

4 Enums

5 Lua utility modules

Lua utility module `EventSequence`

Functions

Class EventSequence

Functions

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Usage:

Class EventSequence

Usage:

Usage:

Parameters:

Usage:

Usage:

Returns:

Usage:

Returns:

Usage:

TombEngine

1 Modules

2 Classes

3 Primitive Classes

4 Enums

5 Lua utility modules

Lua utility module EventSequence

Functions

Class EventSequence

Functions

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Usage:

Class EventSequence

Usage:

Usage:

Parameters:

Usage:

Usage:

Returns:

Usage:

Returns:

Usage:

Lua utility module `EventSequence`